在 Visual Studio 自定義 HTML IntelliSense

TLDR

• 透過編輯 SchemaCatalog.xml 並建立自定義 XSD 檔案，可擴充 Visual Studio 的 HTML IntelliSense。
• 必須將 IsSupplemental 設為 true，HTML IntelliSense 才會生效。
• CustomPrefix 需與自定義屬性的前綴（如 data-）一致。
• 此設定為全域設定，無法針對單一專案設定。
• 更新 Visual Studio 會重置 SchemaCatalog.xml，導致設定失效。

設定方法與限制

當專案使用大量自定義 HTML Attribute（如 data-*）來處理 JavaScript 邏輯時，為避免拼字錯誤或遺漏，可透過擴充 Visual Studio 的 IntelliSense 來輔助開發。

什麼情況下會遇到這個問題

當開發者希望在 Visual Studio 中針對自定義屬性獲得自動補全提示，但 Visual Studio 預設並不包含這些自定義規則時。

設定步驟

1. 找到 SchemaCatalog.xml 檔案，路徑依版本而異：
   • 2019 Community：C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\Extensions\Microsoft\Web Tools\Schemas\HTML\
   • 2022 Community：C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\Extensions\Microsoft\Web Tools\Schemas\HTML
2. 在 SchemaCatalog.xml 中新增 <schema /> 節點以引用自定義的 XSD 檔案：

   <schema File="Wing.xsd" FriendlyName="Wing" IsSupplemental="true" CustomPrefix="data-" />

3. 在同目錄下建立對應的 XSD 檔案。若遇到權限問題，請先在外部建立後再複製進去。
4. 重啟 Visual Studio 即可生效。

WARNING

此設定為全域設定，無法針對特定專案進行配置。此外，每次更新 Visual Studio 時，SchemaCatalog.xml 會被重置，導致自定義設定失效。若不需要某些內建的 IntelliSense（如 AngularJS 或 Aria），可直接將其在 SchemaCatalog.xml 中的引用註解掉。

XSD 檔案結構說明

XSD（XML Schema Definition）定義了 IntelliSense 的觸發條件與顯示內容。

什麼情況下需要理解 XSD 結構

當你需要定義哪些 HTML 標籤（Tag）可以觸發 IntelliSense，以及這些標籤對應的屬性值（Attribute Value）清單時。

關鍵節點說明

• <xsd:element />：設定觸發 IntelliSense 的 HTML 元素。若設為 ___all___，則所有標籤皆會觸發。
• <xsd:complexType />：定義該元素內可包含的屬性群組。
• <xsd:attribute />：定義具體的自定義屬性名稱。
• <xsd:attributeGroup />：將多個屬性定義為群組，方便重複引用。
• <xsd:restriction /> 與 <xsd:enumeration />：用於限制屬性值，提供下拉式選單供開發者選擇。

實作範例

以下為針對自定義 data-* 屬性所撰寫的 XSD 範例：

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:vs="http://schemas.microsoft.com/Visual-Studio-Intellisense"
  vs:ishtmlschema="true">

  <xsd:attributeGroup name="formatAttributeGroup">
    <xsd:attribute name="data-format">
      <xsd:simpleType>
        <xsd:restriction base="xsd:NMTOKEN">
           <xsd:enumeration value="trim" />
           <xsd:enumeration value="lowerCase" />
           <xsd:enumeration value="upperCase" />
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:attribute>
  </xsd:attributeGroup>

  <xsd:element name="input">
    <xsd:complexType>
      <xsd:attributeGroup ref="formatAttributeGroup" />
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

執行後，在編輯器輸入 data- 將觸發提示，選擇 data-format 後會進一步顯示 trim、lowerCase 等預設值。

TIP

此方法特別適用於使用 Unobtrusive JavaScript 的專案，透過在 HTML 中宣告自定義屬性來綁定 JavaScript 事件，利用 XSD 補全功能可大幅提升開發效率並減少拼字錯誤。

異動歷程

1. 2022-11-11

   • 初版文件建立。